home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / public / SciAn / src / README < prev    next >
Text File  |  1994-08-01  |  28KB  |  634 lines

  1. ***************************************************************************
  2. *                                                                         *
  3. *  SciAn README File                                                      *
  4. *  Eric Pepke and Jim Lyons                                               *
  5. *  September 15, 1993                                                     *
  6. *                                                                         *
  7. ***************************************************************************
  8.  
  9. This file describes the process of obtaining and installing SciAn on your
  10. workstation.  Please read it thoroughly before doing any installation.  I
  11. know it's not always much fun to read things before jumping in and compiling,
  12. but please do it anyway--there are some definable options that you need to
  13. know about before you begin.
  14.  
  15. Table Of Contents
  16.  
  17. 1.0  Introduction
  18. 2.0  System requirements
  19.    2.1  FORTRAN option
  20.    2.2  HDF option
  21.    2.3  NetCDF option
  22.    2.4  JPEG option
  23. 3.0  Obtaining and installing SciAn
  24.    3.1  Installing SciAn from the SuperComputing 93 CD-ROM
  25.    3.2  Obtaining SciAn via ftp
  26.       3.2.1  Connecting to ftp.scri.fsu.edu
  27.       3.2.1  Downloading the SciAn Package
  28.    3.3  Installing SciAn
  29.       3.3.1  Preparing the installation options
  30.       3.3.2  Assigning font mappings
  31.       3.3.3  Compiling and linking SciAn
  32.       3.3.4  Releasing SciAn
  33.       3.3.5  Local options
  34. 4.0  Obtaining the documentation
  35.    4.1  PostScript format
  36.    4.2  Microsoft Word format
  37. 5.0  Using the technical notes
  38. 6.0  Getting help
  39.    6.1  Common problems and solutions
  40.  
  41. ---------------------------------------------------------------------------
  42.  
  43. 1.0  Introduction
  44.  
  45. SciAn is a scientific visualization and animation program for Silicon
  46. Graphics and IBM RISC/Sytem 6000 workstations.  It was developed at the
  47. Supercomputer Computations Research Institute at Florida State University
  48. to help meet the daily visualization needs of our scientists.
  49.  
  50. SciAn is primarily intended to do 3-D visualizations of data in an 
  51. interactive environment with the ability to generate animations using
  52. frame-accurate video recording devices.  A user manual, on-line help, and
  53. technical notes will help you use the program.
  54.  
  55. As a research institution, we have always relied upon the availability of
  56. free software to meet our needs, and we wanted to give something back to the
  57. research community in return.  For this reason, we are making SciAn 
  58. available at no charge.
  59.  
  60. If you have problems with or suggestions about SciAn, please don't hesitate
  61. to send us electronic mail.  However, please understand that we are a 
  62. research institution, not a software development company.  We work best in
  63. an environment of cooperation and collaboration, and we hope that you will
  64. join us. Send inquiries about SciAn to scian-info@scri.fsu.edu. You can also
  65. request to be put on the SciAn mailing list, which will keep you informed
  66. of updates.  There is no requirement to sign a license agreement for SciAn,
  67. but it is important to keep track of who is using it, so that we can show
  68. those who fund us that we are doing useful work for the research community.
  69.  
  70. If you use SciAn to produce images or animations for publication, please
  71. give credit to the Supercomputer Computations Research Institute at Florida
  72. State University.  It is a lot easier to justify continuing to put effort
  73. into maintaining SciAn if we can point to places where it is being used to
  74. do real work.
  75.  
  76. 2.0  System requirements
  77.  
  78. SciAn currently runs on two platforms:
  79.   1) Silicon Graphics 4D workstations
  80.   2) IBM RISC/System 6000 workstations
  81.  
  82. Beginning with version 0.60, SciAn should run on all Silicon Graphics Power
  83. Series, Personal IRIS, and Indigo workstations with Z-buffer capability.  It
  84. will not run on very old workstations, such as the 1000, 2000, and 3000
  85. series.
  86.  
  87. SciAn will run only on IBM RISC/System 6000 workstations that have 3-D
  88. graphics accelerators that provide GL compatibility.  SciAn also requires
  89. a Z-buffer.  If there is any question about whether your hardware provides
  90. this, please get in touch with your system manager or IBM sales 
  91. representative.  (IBM makes a bewildering variety of hardware, and I can't
  92. keep up, but the magic words are Z-buffer and 3-D GL compatibility.)
  93.  
  94. On all workstations, SciAn ABSOLUTELY REQUIRES a Z-buffer.  If you try 
  95. to run it on a workstation that does not have a Z-buffer, you will get
  96. strange results.
  97.  
  98. Because SciAn is distributed as source code, you must also have access to
  99. a C compiler to install.  Any old ANSI C will do; you don't need C++.
  100.  
  101. In addition to the basic SciAn, there are several installation options.
  102. The automatic installation process as described in Section 3.3.2 takes
  103. care of detecting and modifying the installation for these options.  
  104. It is necessary to have the correct libraries and languages installed 
  105. before you begin to install SciAn.
  106.  
  107. 2.1  FORTRAN option
  108.  
  109. If a FORTRAN compiler is present on your system, SciAn will use it to
  110. compile the PLOT-3D file reader to be able to read unformatted FORTRAN
  111. data files.  If you don't have a FORTRAN compiler, the PLOT-3D file
  112. reader will only be able to read formatted and binary files.
  113.  
  114. In order to compile using FORTRAN, there must be a FORTRAN compiler in the
  115. /bin, /usr/bin, /usr/local/bin, or . directories.  The name of the FORTRAN
  116. compiler is given in the flags.?.make file as described in section 3.
  117.  
  118. 2.2  HDF option
  119.  
  120. SciAn may also optionally be installed using the Hierarchical Data Format
  121. (HDF) library developed by the National Center for Supercomputing 
  122. Applications at the University of Illinois at Urbana-Champaign.  This library
  123. is available via anonymous FTP from ftp.ncsa.uiuc.edu.  We strongly recommend
  124. that you obtain this library, as it provides a good data format.
  125.  
  126. You must install the HDF library, libdf.a, in /lib, /usr/lib, or 
  127. /usr/local/lib before starting the SciAn installation process.  SciAn will
  128. work with versions 3.1, 3.2, and 3.3 of the HDF library.
  129.  
  130. 2.3  NetCDF option
  131.  
  132. SciAn may optionally be installed using the NetCDF library, which is
  133. available via anonymous FTP from unidata.ucar.edu.  We strongly recommend
  134. that you obtain this library, as it provides a good data format.
  135.  
  136. You must install the NetCDF library, libnetcdf.a, in /lib, /usr/lib, or 
  137. /usr/local/lib before starting the SciAn installation process.  There must
  138. also be a library called librpcsvc.a, which normally comes with the system
  139. software, in /usr/lib.  Silicon Graphics machines must also have the Sun
  140. compatibility library, libsun.a.
  141.  
  142. 2.4  JPEG option
  143.  
  144. The JPEG animation recorder driver provides an easy way to save animation
  145. in a series of compressed JPEG files.  In order to use this, you must
  146. install the JPEG library developed by Rodney Hoinkes at the Centre for 
  147. Landscape Research.  It is available via anonymous ftp from uceng.uc.edu.
  148. There are several libraries available from this site; the one you need
  149. is called libCLRjpeg4.a.  It must be installed in /lib, /usr/lib, or
  150. /usr/local/lib.
  151.  
  152. 3.0  Obtaining and installing SciAn
  153.  
  154. The next three sections describe the process of installing SciAn on your 
  155. machine. If you want to use the files on this CD, read section 3.1 and then
  156. go on to section 3.3. If you want to obtain the very latest version of SciAn
  157. from our ftp site, read section 3.2. Once you have the files on your 
  158. workstation, follow the instructions in section 3.3 to create a SciAn 
  159. executable file.
  160.  
  161. 3.1  Installing SciAn from the SuperComputing 93 CD-ROM
  162.  
  163. This disc contains a directory named "SciAn" with five files:
  164.  
  165. README            This file, describing the installation process
  166. RELEASE.NOTES     Notes about this version of SciAn
  167. scian085.tar.Z    Compressed tar file of the SciAn source files
  168. user080.ps.tar.Z  Compressed tar file of the User's Manual PostScript files
  169. ref080.ps.tar.Z   Compressed tar file of the Reference Manual PostScript files
  170.  
  171. First, make a directory for the SciAn files on your local disk and copy all
  172. five files to it. Then go to the directory and uncompress the source files 
  173. by entering
  174.  
  175.     uncompress scian085.tar
  176.  
  177. When the uncompress command finishes, you will have a file called scian085.tar.
  178. To extract the individual files from the tar file, enter
  179.  
  180.     tar -xvof scian085.tar
  181.  
  182. If you get an error message, try
  183.  
  184.     tar -xvf scian085.tar
  185.  
  186. Many files will be extracted from the SciAn tar file.  Files ending in .c,
  187. .h, and .f are the source files of SciAn.  The Makefile and files with .make
  188. in their names are for the make program.  There is also a directory called
  189. demo which contains demonstration files for SciAn.
  190.  
  191. If you want to print out the documentation, uncompress the two document 
  192. files and extract the individual files from them. Enter
  193.  
  194.     uncompress user080.ps.tar
  195.     tar -xvf user080.ps.tar
  196.  
  197. and
  198.  
  199.     uncompress ref080.ps.tar
  200.     tar -xvf ref080.ps.tar
  201.  
  202. The tar command will produce a number of PostScript files, all ending in the
  203. .ps extension.  You can print out these PostScript files according to the
  204. rules for the printers at your site. (Note that the manuals describe version
  205. 0.80 of the program. You may notice some minor differences from the current
  206. release.)
  207.  
  208. If you are installing from the CD-ROM, skip to section 3.3 now.
  209.  
  210. 3.2  Obtaining SciAn via ftp
  211.  
  212. SciAn is normally distributed via anonymous ftp from ftp.scri.fsu.edu.  If 
  213. you do not have access to anonymous ftp, send us mail, and we'll try to
  214. figure out some other way to get you the program.  It is much easier to
  215. get the program through ftp, however, and it's certainly easier to get
  216. updates that way.
  217.  
  218.  
  219. 3.2.1  Connecting to ftp.scri.fsu.edu
  220.  
  221. Before you connect to the SciAn distribution machine, make sure that you are
  222. in a directory on your machine where you want the SciAn source to reside.  You
  223. will need a few megabytes to keep the files during the installation process.
  224.  
  225. To connect to ftp.scri.fsu.edu, start up ftp on your unix machine like
  226. this:
  227.  
  228.     ftp ftp.scri.fsu.edu
  229.  
  230. When asked for a user name, enter anonymous.  When asked for a password,
  231. enter your network electronic mail address.
  232.  
  233. The SciAn program and documentation are located in the SciAn subdirectory
  234. of the pub directory.  To get into that directory, enter
  235.  
  236.     cd pub/SciAn
  237.  
  238. In that directory, you will find a README file (which is this document)
  239. and several subdirectories.
  240.  
  241. The release subdirectory contains the release versions of SciAn.  Obtaining
  242. SciAn from this directory is described in section 3.2.
  243.  
  244. The beta subdirectory contains versions of SciAn for our beta testers.  These
  245. versions are not as thoroughly tested as the release versions.  When a version
  246. passes beta test, it is moved to the "release" directory.
  247.  
  248. The patches subdirectory contains minor patches to particular versions of 
  249. SciAn which do not require the bother of recompiling the entire source.  You
  250. will receive notice of patches through the SciAn mailing list.
  251.  
  252. The documentation subdirectory contains documentation for SciAn.  Obtaining
  253. and printing it is described in section 4.0.
  254.  
  255. The technotes subdirectory contains technical notes for using SciAn.  These
  256. are text files that contain information about topics that we haven't had time
  257. to put in the manual.
  258.  
  259. 3.2.1  Downloading the SciAn Package
  260.  
  261. In the "release" subdirectory (enter  cd release  to get to the directory)
  262. you will find several files.  They will all have names of the form
  263. scianXXX.tar.Z, where XXX is the version number of SciAn.  For example, the
  264. file scian082.tar.Z contains SciAn version 0.82.
  265.  
  266. It is usually best to get the latest version of SciAn, unless you have 
  267. recieved a note to use an older version.
  268.  
  269. You must download the file in binary mode.  Most versions of ftp figure out
  270. that the target machine is running UNIX and go into binary mode automatically.
  271. Just to make sure, enter
  272.  
  273.     image
  274.  
  275. to put ftp in binary mode.  Now it is time to download SciAn.  Let's assume
  276. that you want to download SciAn version 0.82.  Enter
  277.  
  278.     get scian082.tar.Z
  279.  
  280. After the file has been transferred, you can get out of ftp by entering bye
  281. or quit, depending on the version of ftp you have.  
  282.  
  283. The SciAn distribution is a compressed tar file.  The first step in getting 
  284. the file ready is to uncompress it.  Enter
  285.  
  286.     uncompress scian082.tar
  287.  
  288. When the uncompress command finishes, you will have a file called scian082.tar.
  289. To extract the individual files from the tar file, enter
  290.  
  291.     tar -xvof scian082.tar
  292.  
  293. If you get an error message, try
  294.  
  295.     tar -xvf scian082.tar
  296.  
  297. Many files will be extracted from the SciAn tar file.  Files ending in .c,
  298. .h, and .f are the source files of SciAn.  (Currently, you don't need the
  299. FORTRAN compiler to compile SciAn.)  The Makefile and files with .make
  300. in their names are for the make program.  There is also a directory called 
  301. demo which contains demonstration files for SciAn.  There may also be a file 
  302. called RELEASE.NOTES.  Look in this file to determine special features of the 
  303. version you have just downloaded.
  304.  
  305. 3.3  Installing SciAn
  306.  
  307. Before SciAn can be installed, it must be configured to your machine.  In
  308. order to understand the process of configuration, you must first understand
  309. how the SciAn source is structured.
  310.  
  311. One copy of the SciAn source is used to produce all versions of SciAn.  Which
  312. version is being compiled depends on constants defined in the file machine.h.
  313. At compile time, the file tests constants to see if it is running on an IBM
  314. or a Silicon Graphics machine and adjusts automatically.  However, there are
  315. several options that you need to set by hand.
  316.  
  317. There are four basic steps in installing SciAn:
  318.  
  319. 1) Prepare the installation options by entering make INSTALL.  Read everything
  320.    the computer prints to the console.  If there is an error which will cause
  321.    problems later on in the installation, it will be described in a message,
  322.    and you will need to fix the error and repeat this step.
  323. 2) Assign font mappings for special characters according to the fonts on
  324.    your computer.
  325. 3) Compile and link SciAn by entering make scian (or pmake scian on Silicon
  326.    Graphics machines with more than one processor).  
  327. 4) Release SciAn by moving the scian executable and the demo files to the
  328.    appropriate directories.
  329.  
  330. These steps are described in the following four sections, 3.3.1 through
  331. 3.3.4.  They should work for nearly all installations.  Some sites may have
  332. local options, such as locally developed additions to SciAn.  Information
  333. on this is described in section 3.3.5.
  334.  
  335. 3.3.1  Preparing the installation options
  336.  
  337. When all the supplemental libraries as described in section 2 have been
  338. installed, the first basic step in installation is to prepare the 
  339. installation options.  This is an extremely important step, and if you 
  340. forget to do it, you may get link errors later.  Enter
  341.  
  342.     make INSTALL
  343.  
  344. A program called ScianPreInstall will go through the options defined in
  345. machine.h and check to make sure that the libraries that are needed are 
  346. present on your system.
  347.  
  348. When ScianPreInstall runs, it will ask you questions and print some messages
  349. to the console.  Read everything it prints!  ScianPreInstall will tell you if
  350. there is anything that needs to be changed in the optional libraries.
  351. Do not proceed to the next step until ScianPreInstall tells you that it is OK
  352. to do so.
  353.  
  354. ScianPreInstall also writes several important files, which will be included
  355. into the source code and make file when you make scian.
  356.  
  357. If and only if make INSTALL has given you the go-ahead to compile, you can go
  358. on to the next step.
  359.  
  360. 3.3.2  Assigning font mappings
  361.  
  362. The next step in the installation is to assign font mappings.  SciAn uses
  363. some characters in the Silicon Graphics font library which are outside the
  364. normal range of ASCII characters.  Unfortunately, which characters are
  365. which has changed as new versions of the operating system and the font
  366. manager have come out.  It is necessary for you to tell SciAn what the
  367. mappings are.  To do this, enter
  368.  
  369. make FONTS
  370.  
  371. at the console.  If you are running on a Silicon Graphics workstation,
  372. you MUST be at a graphics console when doing this.  On all other machines
  373. this will just produce a message and generate a file, and you can go on
  374. to the next step.  On the Silicon Graphics, this will run a program that
  375. will put up a window which will ask you to find the various characters.
  376. Follow the directions given to you by the program, and then you will be
  377. able to go on to compiling SciAn.
  378.  
  379. This step really only needs to be done when you install SciAn for the first
  380. time, or when you do an upgrade of the operating system which changes the
  381. characters in the fonts.  If you are having any trouble with special 
  382. characters within SciAn, e.g., the copyright C in a circle doesn't appear
  383. on the Copyright help screen, then you must do this step and recompile 
  384. SciAn.
  385.  
  386. You can omit this step entirely, in which case a set of default mappings will 
  387. be used.  The default mappings will probably work on your system, unless you
  388. are running an old version of the operating system.  If not, the worst that
  389. can happen is that you won't be able to see some special characters.
  390.  
  391. 3.3.3  Compiling and linking SciAn
  392.  
  393. To make SciAn, enter
  394.  
  395.     make scian
  396.  
  397. If you are making on a Silicon Graphics machine with more than one processor,
  398. you can do a parallel make instead by entering
  399.  
  400.     pmake scian
  401.  
  402. The makefile will compile and link SciAn resulting in an executable named 
  403. scian.  If you get any kind of error, make sure that the configuration is
  404. set up correctly as described in sections 3.3.1 and 3.3.2.  If that doesn't
  405. help, read through section 6.1.  If you still cannot figure out what is 
  406. wrong, send mail to us at scian-bugs@scri.fsu.edu.
  407.  
  408. When scian has been made, test it out by typing ./scian.  The user manual
  409. has a brief tour, but if you don't have a copy of the manual, you can get
  410. on-line help by clicking the mouse in the title window.
  411.  
  412. 3.3.4  Releasing SciAn
  413.  
  414. The final step in installing SciAn is to release it to the users of your
  415. machine.
  416.  
  417. First copy the scian executable file to a place where users can reach it.
  418. One good place to put it is in /usr/local/bin.
  419.  
  420. Then copy or move the demo directory to some directory where users can reach
  421. it and tell your users where it is.  The user manual refers to this directory,
  422. so your users need to know its location.
  423.  
  424. The executable of the Silicon Graphics version of SciAn should run on any
  425. Silicon Graphics workstation.  However, the IBM RS/6000 version will probably
  426. only run on workstations configured in a similar way to the workstation where
  427. it was compiled.  If you are running in a heterogeneous environment with 
  428. several different versions of AIX, you may need to keep several executables
  429. of SciAn.
  430.  
  431. 3.3.5  Local options
  432.  
  433. Although the standard installation process works for most people, some
  434. sites may have unusual setups that require modification to work.  This 
  435. section gives some hints for possible configuration requirements.
  436.  
  437. In order to understand how to do this, you need to know a little about
  438. how the installation process works.  Running make INSTALL compiles and
  439. executes a program called ScianPreInstall.  This program determines 
  440. what kind of machine it has been compiled on (using the include file
  441. machine.h).  Currently, two machine types are recognized: IBM RS/6000
  442. workstations, and Silicon Graphics workstations.  These are called
  443. "ibm6k" and "sgi4d" respectively.
  444.  
  445. Once SciAn PreInstall determines the basic machine type, it looks at a 
  446. number of installation source files, each containing the name of the 
  447. machine type.  Currently, these files are the following:
  448.  
  449. flags.ibm6k.make
  450. flags.sgi4d.make
  451. flfiles.ibm6k.make
  452. flfiles.sgi4d.make
  453. lfiles.ibm6k.make
  454. lfiles.sgi4d.make
  455.  
  456. The flags.*.make files contain symbol definitions that are included in
  457. the Makefile.  These give the names of the C and FORTRAN compilers and
  458. compilation and linking options.
  459.  
  460. The lfiles.*.make files contain the names of link libraries, 
  461. one per line, that are required for standard linking.  The flfiles.*.make 
  462. files contain the names of link libraries, one per line, that are required
  463. for linking when FORTRAN has been used.  All libraries are the names that
  464. will be used with the -l flag when linking.  For example, a library that
  465. appears in flags.sgi4d.make as gl_s refers to the library libgl_s.a and
  466. results in a flag -lgl_s on the link line.
  467.  
  468. The search paths for link libraries and compilers, as well as the names of
  469. the optional libraries, are currently hard-coded into the beginning of
  470. ScianPreInstall.c.
  471.  
  472. In addition, ScianPreInstall reads the file machine.local.h, if present.
  473. This contains lines to be included into the C source, such as #define
  474. constants.
  475.  
  476. ScianPreInstall.c produces a number of files (lfiles.make, flfiles.make, 
  477. and flags.make) that are directly included in the Makefile.  In addition,
  478. it produces a number of include files (machine.extras.h, machine.hdf.h, 
  479. machine.jpeg.h, etc.) which specify compilation options for SciAn.
  480.  
  481. The names of the C and FORTRAN compilers are specified in the flags.sgi4d.
  482. make or flags.ibm6k.make, whichever is appropriate.  By default they are 
  483. cc and f77, respectively.  To change the names, change them in this file 
  484. and make INSTALL again.  The C compiler is also used to link SciAn.
  485.  
  486. To add to the search path for header files or libraries, change the CFLAGS,
  487. FFLAGS, or LFLAGS symbols in flags.<machinetype>.make and make INSTALL 
  488. again.  If the new search path is used for one of the SciAn optional 
  489. libraries such as HDF, you may also need to edit the ScianPreInstall 
  490. source code before  doing make INSTALL.
  491.  
  492. If you are compiling on an IBM RS/6000 machine, you may need to define the
  493. MENUSFROM0 constant in machine.h.  The numbering of menu items in GL is 
  494. supposed to start at 1.  However, some versions of the IBM GL emulation, 
  495. such as with AIX 3.1.5, start at 0.  There isn't really any way to tell 
  496. this beforehand, but if you compile SciAn and notice that the wrong menu 
  497. items are getting grayed, you will need to go back and change this.
  498.  
  499. 4.0  Obtaining the documentation
  500.  
  501. Documentation can be downloaded in two forms: PostScript files and Macintosh 
  502. files for Microsoft Word 5.
  503.  
  504. 4.1  PostScript format
  505.  
  506. PostScript files for the manuals are located in the documentation subdirectory.
  507. The name of the user manual is of the form userXXX.ps.tar.Z, and the name
  508. of the reference manual is of the form refXXX.ps.tar.Z, where XXX is the 
  509. version of SciAn.  For example, for version 0.80 of SciAn, there is a user 
  510. manual named user080.ps.tar.Z and a reference manual named ref080.ps.tar.Z.
  511. There may also be a file of the form colorXXX.ps.tar.Z, which contains a
  512. color plate that can be printed out on a color PostScript printer.
  513.  
  514. Each file is a compressed tar file, similar to the file containing the 
  515. SciAn software, as described in section 3.  Make sure that ftp is using
  516. the binary format by typing 'image' and then download the files.  After you
  517. exit ftp, uncompress the files using the uncompress command.  Then use the
  518. tar command to extract the files from the archive.  For example:
  519.  
  520. uncompress user080.ps.tar
  521. tar xvf user080.ps.tar
  522.  
  523. The tar command will produce a number of PostScript files, all ending in the
  524. .ps extension.  You can print out these PostScript files according to the 
  525. rules for the printers at your site.
  526.  
  527. 4.2  Microsoft Word format
  528.  
  529. Microsoft Word files are located in the documentation subdirectory.  The
  530. name of the user manual is of the form userXXX.msw.sit.hqx, and the name
  531. of the reference manual is of the form refXXX.msw.sit.hqx, where XXX is 
  532. the version of SciAn.  For example, version 0.80 of SciAn has a user manual
  533. named user080.msw.sit.hqx and a reference manual named ref080.msw.sit.hqx.
  534. There may also be a file of the form color080.msw.sit.hqx, which contains a
  535. color plate that can be printed out on a color printer.
  536.  
  537. The manual is in Macintosh Word 5 format and has been compressed and
  538. encoded with Stuffit.  Use BinHex4 or StuffIt to decode the file and
  539. then use StuffIt to extract the archive.  When printing the manual, be
  540. sure to check "Color/Grayscale" in the print dialog. Printing the manual 
  541. requires a lot of memory, so it may be necessary to increase the amount of
  542. memory used by Word. If you use background printing, it may be necessary to
  543. quit all other open applications. If you still have problems, try printing
  544. the manual in sections.
  545.  
  546. 5.0  Using the technical notes
  547.  
  548. When we need to release information about some aspect of SciAn that cannot
  549. wait for the long time delay in releasing a new version of the manual, we will
  550. put a technical note in the technotes directory.  A file called INDEX will
  551. give summaries of all the technical notes in the directory.
  552.  
  553. Technical notes are not guaranteed to be easy to understand and may cover
  554. esoteric topics.
  555.  
  556. 6.0  Getting help
  557.  
  558. We hope you enjoy SciAn.  If you have difficulty installing it, please 
  559. first check through this file to make sure that you are doing everything
  560. correctly.  Be sure to look through section 6.1.  If you still have problems,
  561. send a message to scian-bugs@scri.fsu.edu.
  562.  
  563. If you have suggestions for new features for SciAn, please send them to 
  564. scian-bugs@scri.fsu.edu.  Please keep in mind that we are a research program
  565. and not a software house, and we work better in collaboration with you.
  566.  
  567. 6.1  Common problems and solutions
  568.  
  569. This section contains some problems that a few people have had during 
  570. installation or printing of the manual.  Please check this section if you
  571. have a problem.
  572.  
  573. PROBLEM: I get link errors.
  574.  
  575. SOLUTION: About 95% of the time this is due to forgetting to do make INSTALL
  576. before doing make scian.  Make INSTALL is a very, very important part of 
  577. the installation process.  It will set up the link files to link properly
  578. if it can and will tell you what to do to fix it if it can't.
  579.  
  580.  
  581. PROBLEM: When I link, I see a message saying that ScianFontMapper.h can't
  582. be found.
  583.  
  584. SOLUTION: This indicates that you haven't gone through the 'make FONTS'
  585. process to generate the font mappings.  See section 3.3.3
  586.  
  587.  
  588. PROBLEM: When I link, I get DFSDgetmaxmin or DFSDgetrange undefined.
  589.  
  590. SOLUTION: Between versions 3.1 and 3.2 of the NCSA HDF library, they changed
  591. the name of one of the routines from DFSDgetmaxmin to DFSDgetrange.  SciAn
  592. can link using either, but you have to specify in machine.h.  Look for 
  593. constants beginning with the letters HDF.  The make INSTALL process will tell
  594. you if SciAn is correctly configured for the right version of HDF.
  595.  
  596.  
  597. PROBLEM: When I print the manual, the figures come out funny!
  598.  
  599. SOLUTION: Make sure you are using the latest version of the Apple laser
  600. printer drivers, and turn background printing off.
  601.  
  602.  
  603. PROBLEM: SciAn compiles fine on the IBM, but when I run it, I get an error 
  604. and it exits.
  605.  
  606. SOLUTION: This one can mean a wide range of things, from trivial to 
  607. disastrous.  In ascending order of difficulty, these are some of the things
  608. we have run into:
  609.  
  610. 1) When a user brings up X, some versions of AIX assume that the user "owns"
  611.    the GL emulator and does not allow anyone else to use it.  Make sure that
  612.    you are the user that ran xinit.
  613. 2) Binaries compiled under different versions of the operating system will
  614.    not run on other versions.  (Also see MENUSFROM0 in machine.h.)  Make 
  615.    sure that you have compiled and run on the same machine.
  616. 3) There are some software configurations that prevent you from using the
  617.    GL emulator from within X.  Check with your system manager to see if this
  618.    is the case.
  619. 4) If you have multiple versions of the X library, the search path specified
  620.    may get the wrong one.  If this is the case, change the order of the
  621.    directories in lfiles.ibm6k.make and rerun make INSTALL.  DO NOT change
  622.    lfiles.make; it is written by make INSTALL.
  623. 5) SciAn does not run on every IBM system, only on those with graphics 
  624.    accelerators that can do 3-D GL emulation, have Z-buffers, and can 
  625.    do RGB color.
  626.  
  627. PROBLEM: When I try to run it on the IBM, the wrong menu items appear to 
  628. highlight, and the fonts don't work in text boxes on the screen.
  629.  
  630. SOLUTION: This probably means that you have compiled under AIX 3.1.5 without
  631. defining MENUSFROM0 in machine.h.  Take a look at machine.h, run "make INSTALL"
  632. again, and try to make again.  This problem is further explained in section
  633. 3.3.1.
  634.